\chapter{How to set a client/server authenticated channel}
\label{cha: Tomcat}

\section{What is Tomcat?}


Tomcat is the web and application server of the Jakarta project, we
call it server as it manages HTTP requests and responses with its HTTP connector.
Tomcat is a web server with support for servlets and JSP, it includes the Jasper
compiler that compiles JSPs turning them into servlets. The Tomcat servlet engine often
occurs in combination with the Apache web server.

Tomcat web server can function as its own. In the beginning there was the perception that the
use of Tomcat was only recommended for development environments and
environments with a minimum speed and transaction management. Today, that
perception no longer exists and Tomcat is used as a standalone web server in environments with high
traffic and high availability.

Since Tomcat is written in Java,it runs on any operating system that has the
Java virtual machine.

\begin{figure}[h]
\begin{centering}
\includegraphics[width=1\textwidth]{b-tomcat.png}
\caption{Default Tomcat home page}
\label{fig:tomcat}
\end{centering}
\end{figure}

\section{Directories}

\begin{itemize}
  \item \textbf{bin:} This directory contains the startup and shutdown scripts
  for both Windows and Linux.
  \item \textbf{conf:} This directory contains the main configuration files for
  Tomcat. The two most important are the server.xml and the global web.xml .
  \item \textbf{server:} This directory contains the Tomcat Java Archive files.
  \item \textbf{lib:} This directory contains Java Archive files that Tomcat is
  dependent upon.
  \item \textbf{logs:} This directory contains Tomcat's log files.
  \item \textbf{src:} This directory contains the source code used by the Tomcat
  server. Once Tomcat is released, it will probably contain interfaces and abstract classes only.
  \item \textbf{webapps:} All web applications are deployed in this directory;
  it contains the WAR file.
  \item \textbf{work:} This is the directory in which Tomcat will place all
  servlets that are generated from JSPs. If you want to see exactly how a
  particular JSP is interpreted, look in this directory.
\end{itemize}

\section{Server.xml}

The server.xml, which is in the folder "conf", defines the behavior of Tomcat
servlet / JSP container. The document is organized into the following categories:

\begin{itemize}
  \item Top Level Elements: $<$Server$>$ is the root element of the entire
  configuration file, while $<$Service$>$ represents a group of Connectors that
  is associated with an Engine.
  \item Top Level Elements: $<$Server$>$ is the root element of the entire
  configuration file, while $<$Service$>$ represents a group of Connectors that
  is associated with an Engine.
  \item Connectors: Represents the interface between external clients sending requests
  and are a particular service. This group will focus on us then to establish HTTPS connections.
  \item Containers: Represents the components responsible for processing incoming requests
  and create the corresponding responses. An Engine handles all requests for service, a
  Host handles all requests for a particular virtual host and a Context handles all requests
  for a specific Web application.
  \item Nested Components: Elements can be nested inside a Container. Some items can only
  be nested in Container, while others can only be nested in a context.
\end{itemize}

Then for every element specifies a series of
introductions, attributes, nested components and special features.

\section{Setting up a HTTPS connection}

We have already seen in what is an HTTPS connection and its theoretical
background. Below are the necessary steps for establishing a secure
authenticated client / server.

\subsection{Tomcat's connector}

The main changes  to be made  are in the file named-above "Server.xml" file,
more specifically in the definition of the Connector of the port 8443 (the
default for HTTPS connections). The Connector tag should look like this:

\begin{lstlisting}[caption=Definition of the Connector of the port
8443 for establishing a HTTPS connection,language=XML]
<Connector clientAuth="true" port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
minSpareThreads="25" maxSpareThreads="75" enableLookups="true" disableUploadTimeout="true"
acceptCount="100" debug="0" maxThreads="200" scheme="https" secure="true" SSLEnabled="true"
keystoreFile="E:\Baul\keystore\192.168.1.100.jks" keystoreType="JKS" keystorePass="password"
truststoreFile="E:\Baul\keystore\192.168.1.100.jks" truststoreType="JKS" truststorePass="password"
sslProtocol="TLS" />
\end{lstlisting}

The following explains the most important attributes. First, the attribute
\textit{clientAuth = "true"}  states that, unlike that it usually happens,
in this case  it is also required client authentication. Then the
set of attributes \textit{scheme = "https" , secure = "true" , SSLEnable =
"true" , sslProtocol = "TLS"} serves to specify the security protocol that we
implement for this Connector.

Then, it is declared both keystore and trustore. Here we must emphasize two things,
firstly the "common
name" of the server's public certificate must be equal to its address in order
to be interpreted by Android, otherwise it won't be accepted. Secondly, we
specify the password for accessing keystores. It was decided that this password is
the user's PIN code. The key store type supported by Tomcat Java KeyStore (JKS).

\subsection{Host}

On a mobile phone running Android operating system will have to follow certain
guidelines when establishing an HTTPS connection:

\begin{itemize}
  \item The keystore and truststore must be stored in the format provided
  by the security provider used in this thesis, ie the BouncyCastle. The
  format is called BouncyCastle Key Store (BKS). Given that this format is
  less common compared to others, like the JKS, is common to use
  key conversion tools such as Portecle (REFERENCE).
  In our case we have chosen to generate all the certificates and stores
  using the tool "KeyTool".
  \item The trustStore  and keystore and must be stored, as any Android
  resource, under the "res" directory, and more specifically in the "raw"
  subdirectory.
  \item As mentioned above it should be noted that the "common name" of the
  server's public certificate must be exactly the same as the server's
  network address. In this case, "192.168.1.100" (Selected througth Tether
  application).
  
\end{itemize}

\subsection{Generation and issuing of certificates}

As mentioned above, there are other methods or programs for the creation and
storage of certificates, such as "Simple Authority" (REFERENCE) and Portecle
(REFERENCE). In this thesis, however, we have chosen to use the tool
"KeyTool'' (REFERENCE), allowing us to learn more about the parameters and
steps necessary for the proper management of certificates on a system with mutual authentication.
First, the server key store is crated,  Figure ~\ref{fig:b1}. As we can see
the \textit{-genkey} command (Generating a new key pair), adds interesting
parameters such as:
\begin{itemize}
  \item  Symmetric encryption algorithm \textit{-keyalg}. In our case, we
  choose RSA.
  \item Server Attributes \textit{cn, ou, c,}. Note that cn is the net adress
  of the server, this is an Android requirement.
  \item Server alias \textit{-alias}: we must be careful with this parameter,
  it must be the same throughout the whole process, otherwise, it can cause
  errors difficult to detect.
  \item Path where storing the key pair \textit{-keystore}.
  \item Password \textit{-storepass} to access the keystore (this password is
  the same as the user is prompted at the start of the application).
  \item Period of validity of the key pair \textit{-validity}.
\end{itemize}

\begin{figure}[h]
\begin{centering}
\includegraphics[width=1\textwidth]{b-1-server-keystore.png}
\caption{Creation of server's keystore}
\label{fig:b1}
\end{centering}
\end{figure}

Then  it is exported a server's public certificate, using the newly generated
key pair. Note that we are maintaining the alias (server). Furthermore, the
certificate is given the format (. cer). To carry out this action is necessary
to enter the previously generated password. See Figure ~\ref{fig: b2}.

\begin{figure}[h]
\begin{centering}
\includegraphics[width=1\textwidth]{b-2-export-server-keystore.png}
\caption{Exporting a server's public certificate}
\label{fig: b2}
\end{centering}
\end{figure}

Similarly, we repeat the process but this time on the host side (client), shown
in Figure ~\ref{fig:b3}. The procedure is the same except for a few details:

\begin{itemize}
  \item The keystore must be stored in
  the subdirectory "raw" in the resources folder of the Android's application.
  \item It is necessary to have BouncyCastle as the security provider is  (more
  efficient cryptographic libraries that make cryptographic methods available to less
  capable devices). This directly affects the format of the keystore, becoming
  BKS. It is also necessary to provide the path to the jar file of the security
  provider.
\end{itemize}


\begin{figure}[h!]
\begin{centering}
\includegraphics[width=1\textwidth]{b-3-client-keystore.png}
\caption{Creation of client's keystore}
\label{fig:b3}
\end{centering}
\end{figure}

For client authentication, it is neccesary to run the command
\textit{-selfcert} so that the client can be correctly identified through self
signed certificates.

\begin{figure}[h!]
\begin{centering}
\includegraphics[width=1\textwidth]{b-4-selfcert-client-keystore.png}
\caption{Setting a client's self signed certificate}
\label{fig:b4}
\end{centering}
\end{figure}

Then, as done previously with the server, we proceed to create a public
certificate and place it in a folder for later access.

\begin{figure}[h!]
\begin{centering}
\includegraphics[width=1\textwidth]{b-5-export-client-keystore.png}
\caption{Exporting a server's public certificate}
\label{fig:b5}
\end{centering}
\end{figure}

Then we will store the client's public certificate in the  server keystore.
So when a connection is being established, the client sends its
certificate, and since the two certificates will be the same, the server trusts
the client and the client is successfully authenticated.

\begin{figure}[h!]
\begin{centering}
\includegraphics[width=1\textwidth]{b-6-import-client2server-keystore.png}
\caption{Importing client's public certificate in server's truststore}
\label{fig:b6}
\end{centering}
\end{figure}

Now the same operation in reverse. This part is used much more than client-side
authentication. For example, browsers store all the certificates of the servers
that they connect via an HTTPS connection. Whenever thay want to communicate
with a server through a secure connection, thay check the coincidence of the
received certificate with the stored one. If the client does not have the
server's certificate, the browser will launch a security exception.

\begin{figure}[h!]
\begin{centering}
\includegraphics[width=1\textwidth]{b-7-import-server2client-keystore.png}
\caption{Importing server's public certificate in client's truststore}
\label{fig:b7}
\end{centering}
\end{figure}

Finally we check the contents of each keystore. Thus, we can verify the type of
keystore and each of their entries. In each case we see that we have an entry
for the private key and other for the public certificate previously imported.

\begin{figure}[h!]
\begin{centering}
\includegraphics[width=1\textwidth]{b-8-list-server.png}
\caption{Server's stored certificates}
\label{fig:b8}
\end{centering}
\end{figure}

Lastly, here we can see client's entries.

\begin{figure}[h!]
\begin{centering}
\includegraphics[width=1\textwidth]{b-9-list-client.png}
\caption{Client's stored certificates}
\label{fig:b9}
\end{centering}
\end{figure}

\subsection{Belgian electronic identity card's certificates}

As stated above, the client is identified by the Belgian electronic
identity card. This is a micro SC Card inserted in
the phone. Officially, this type of identity cards have not been issued yet,
so in this thesis we are using SD cards with installed applets that provide
the functionality that would provide the original identity cards. One limitation
of this way of proceeding is that every time this applet is loaded, it randomly
generates a new key pair. Remembering the previous sections, this makes it
impossible that the server can store on client certificates to authenticate it.
That is why we have produced a set of public keys manually, and distributed the certificates held by them.
